Composer CMS: Content Make System

Gary B. Genett

v3.1 (2022-05-11)

Composer CMS

Composer Icon “Creating Made Simple.”
Composer CMS v3.1 License: GPL
Gary B. Genett composer@garybgenett.net

Overview

Composer is a simple but powerful CMS based on [Pandoc], [Bootstrap] and [GNU Make]. It is a document and website build system that processes directories or individual files in [Markdown] format.

Traditionally, CMS stands for Content Management System. Composer is designed to be a Content Make System. Written content is vastly easier to manage as plain text, which can be crafted with simple editors and tracked with revision control. However, professional documentation, publications, and websites require formatting that is dynamic and feature-rich.

[Pandoc] is an extremely powerful document conversion tool, and is a widely used standard for processing [Markdown] into other formats. While it has reasonable defaults, there are a large number of options, and additional tools are required for some formats and features.

Composer consolidates all the necessary components, simplifies the options, and prettifies the output formats, all in one place. It also serves as a build system, so that large repositories can be managed as documentation archives or published as [Bootstrap Websites].

Composer Icon Composer Screenshot

Quick Start

Use make help to get started:

make [-f .../Makefile] [variables] <filename>.<extension>
make [-f .../Makefile] [variables] <target>

Fetch the necessary binary components (see Requirements):

make _update-all

Create documents from source [Markdown] files (see Formatting Variables):

make README.html
make Composer-v3.1.Manual.html c_list="README.md LICENSE.md"

Save a persistent configuration (see [Recommended Workflow], [Configuration Settings] and Special Targets):

make template >.composer.mk
$EDITOR .composer.mk
    book-Composer-v3.1.Manual.html: README.md LICENSE.md
make clean
make all

Recursively install and build an entire directory tree (see [Recommended Workflow]):

cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all

See help-all for full details and additional targets.

Principles

The guiding principles of Composer:

  • All source files in readable plain text
  • Professional output, suitable for publication
  • Minimal dependencies, and entirely command-line driven
  • Separate content and formatting; writing and publishing are independent
  • Inheritance and dependencies; global, tree, directory and file overrides
  • Fast; both to initiate commands and for processing to complete

Direct support for key document types (see [Document Formatting]):

  • [HTML] & [Bootstrap Websites]
  • [PDF]
  • [EPUB]
  • [Reveal.js Presentations]
  • [Microsoft Word & PowerPoint]

Requirements

Composer has almost no external dependencies. All needed components are integrated, including [Pandoc]. The repository needs to be initialized with [_update-all] to fetch the [Pandoc] and [YQ] binaries (see [Repository Versions]).

Composer does require a minimal command-line environment based on [GNU] tools, particularly [GNU Make], which is standard for all [GNU/Linux] systems. The [Windows Subsystem for Linux] for Windows and [MacPorts] for macOS both provide suitable environments.

The one large external requirement is [TeX Live], and it can be installed using the package managers of each of the above systems. It is only necessary for creating [PDF] files.

Below are the versions of the components in the repository, and the tested versions of external tools for this iteration of Composer. Use [check] to validate your system.

Repository Commit License
[Pandoc] 2.18 GPL
[YQ] v4.24.2 MIT
[Bootstrap] v5.1.3 MIT
[Markdown Viewer] 059f3192d4ebf5fa9776 MIT
[Reveal.js] 4.3.1 MIT
Project Composer Version
GNU Bash 5.0.18
- GNU Coreutils 8.31
- GNU Findutils 4.8.0
- GNU Sed 4.8
[GNU Make] 4.2.1
- [Pandoc] 2.18
- [YQ] 4.24.2
- [TeX Live] (pdf) 2021 3.14159 2.6-1.40.22

[Markdown Viewer] is included both for its CSS stylesheets, and for real-time rendering of [Markdown] files as they are being written. To install, follow the instructions in the README.md, and select the appropriate manifest.*.json file for your browser.

The versions of the integrated repositories can be changed, if desired (see [Repository Versions]).

Composer CMS v3.1 :: Help

make [-f .../Makefile] [variables] <filename>.<extension>
make [-f .../Makefile] [variables] <target>

Composer Variables

Formatting Variables

Variable Purpose Value
[c_type] ~ T Desired output format html
[c_base] ~ B Base of output file README
[c_list] ~ L List of input files(s) README.md
[c_lang] ~ g Language for document headers en-US
[c_css] ~ s Location of CSS file (.composer.css)
[c_toc] ~ c Table of contents depth
[c_level] ~ l Chapter/slide header level 2
[c_margin] ~ m Size of margins ([PDF]) 0.8in
[c_options] ~ o Custom Pandoc options
Values: c_type Format Extension
html HyperText Markup Language *.html
pdf Portable Document Format *.pdf
epub Electronic Publication *.epub
revealjs Reveal.js Presentation *.revealjs.html
docx Microsoft Word *.docx
pptx Microsoft PowerPoint *.pptx
text Plain Text (well-formatted) *.txt
markdown Pandoc Markdown (for testing) *.md.txt
  • Other [c_type] values will be passed directly to [Pandoc]
  • Special values for [c_css]:
    • css_alt ~ Use the alternate default stylesheet
    • 0 ~ Revert to the [Pandoc] default
  • Special value 0 for [c_toc] ~ List all headers, and number sections
  • Special value 0 for [c_level] ~ Varies by [c_type] (see [help-all])
  • An empty [c_margin] value enables individual margins:
    • c_margin_top ~ mt
    • c_margin_bottom ~ mb
    • c_margin_left ~ ml
    • c_margin_right ~ mr

Control Variables

Variable Purpose Value
[MAKEJOBS] Parallel processing threads 1 (makejobs)
[COMPOSER_DOCOLOR] Enable title/color sequences (boolean)
[COMPOSER_DEBUGIT] Use verbose output (debugit)
[COMPOSER_INCLUDE] Include all: .composer.mk (boolean)
[COMPOSER_DEPENDS] Sub-directories first: [all] (boolean)
[COMPOSER_LOG] Timestamped command log .composed
[COMPOSER_EXT] Markdown file extension .md
[COMPOSER_TARGETS] See: [all]/[clean] [config]/[targets]
[COMPOSER_SUBDIRS] See: [all]/[clean]/[install] [config]/[targets]
[COMPOSER_IGNORES] See: [all]/[clean]/[install] [config]
  • [MAKEJOBS] ~ c_jobs ~ J
  • [COMPOSER_DOCOLOR] ~ c_color ~ C
  • [COMPOSER_DEBUGIT] ~ c_debug ~ V
  • (makejobs) = empty is disabled / number of threads / 0 is no limit
  • (debugit) = empty is disabled / any value enables / 0 is full tracing
  • (boolean) = empty is disabled / any value enables

Composer Targets

Primary Targets

Target Purpose
[help] Basic help overview (default)
[help-all] Console version of README.md (mostly identical)
[template] Print settings template: .composer.mk
[compose] Document creation engine (see Formatting Variables)
[site] Recursively create [Bootstrap Websites]
[install] Current directory initialization: Makefile
[install-all] Do [install] recursively (no overwrite)
[install-force] Recursively force overwrite of Makefile files
[clean] Remove output files: [COMPOSER_TARGETS] :: [*-clean]
[clean-all] Do [clean] recursively: [COMPOSER_SUBDIRS]
[*-clean] Any targets named this way will also be run by [clean]
[all] Create output files: [COMPOSER_TARGETS] :: [*-all]
[all-all] Do [all] recursively: [COMPOSER_SUBDIRS]
[*-all] Any targets named this way will also be run by [all]
[list] Print updated files: *.md >> .composed

Special Targets

There are a few targets considered Specials, that have unique properties:

Base Name Purpose
[book] Concatenate a source list into a single output file
[page] (Reserved for the future [site] feature)
[post] (Reserved for the future [site] feature)

For each of these base names, there are a standard set of actual targets:

Target Purpose
%s-clean Called by [clean], removes all %-* files
%s-all Called by [all], creates all %-* files
%s Main target, which is a wrapper to %s-all
%-* Target files will be processed according to the base

Additional Targets

Target Purpose
[debug] Diagnostics, tests targets list in [COMPOSER_DEBUGIT]
[debug-file] Export [debug] results to a plain text file
[check] List system packages and versions (see Requirements)
[check-all] Complete [check] package list, and system information
[config] Show values of all Composer Variables
[config-all] Complete [config], including environment variables
[targets] List all available targets for the current directory
[_commit] Timestamped [Git] commit of the current directory tree
[_commit-all] Automatic [_commit], without $EDITOR step
[_release] Full upgrade to current release, repository preparation
[_update] Update all included components (see Requirements)
[_update-all] Complete [_update], including binaries: [Pandoc], [YQ]

Command Examples

Fetch the necessary binary components (see Requirements):

make _update-all

Create documents from source [Markdown] files (see Formatting Variables):

make README.html
make Composer-v3.1.Manual.html c_list="README.md LICENSE.md"

Save a persistent configuration (see [Recommended Workflow], [Configuration Settings] and Special Targets):

make template >.composer.mk
$EDITOR .composer.mk
    book-Composer-v3.1.Manual.html: README.md LICENSE.md
make clean
make all

Recursively install and build an entire directory tree (see [Recommended Workflow]):

cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all

See help-all for full details and additional targets.

Happy Making!